home *** CD-ROM | disk | FTP | other *** search
/ MacFormat 1995 June / MacFormat 25.iso / Shareware City / Developers / HoW Developer’s Kit 1.2 / HoWSample / HoWSample Help / HoWSample Help.rsrc / STR#_1026.txt < prev    next >
Encoding:
Text File  |  1994-10-17  |  4.1 KB  |  149 lines
  1. 
  2.  
  3. 
  4.  
  5. ⌃
  6.  
  7. ⌃
  8.  
  9. åRequirements
  10.  
  11. 
  12.  
  13. 
  14.  
  15. The current version of the Help on Wheels developer‚Äôs kit is available only
  16.  
  17. for use with MPW C and C++.  MPW Pascal developers can use the kit with
  18.  
  19. a little work, since it uses Pascal calling conventions.  The next version
  20.  
  21. will support Think C projects.
  22.  
  23. 
  24.  
  25. 
  26.  
  27. Help on Wheels uses several Toolbox managers which are new to System
  28.  
  29. 7, such as the Alias Manager, the Process Manager, and the Apple Event
  30.  
  31. Manager.  Therefore, it does not work under System 6 or earlier
  32.  
  33. versions, and any attempt to register a client will be met with an error
  34.  
  35. code.  (Later versions of Help on Wheels and its client interface library
  36.  
  37. will operate under System 6 in a reduced mode, where the server deals
  38.  
  39. only with help files and does not talk back to clients.)
  40.  
  41. 
  42.  
  43. To be a client of the help server, an application must be System 7
  44.  
  45. friendly.  This is because the client engine and server converse using
  46.  
  47. Apple events.  Once you set the bit in your application‚Äôs 'SIZE' resource to
  48.  
  49. allow this behavior, Finder assumes that you support the Required suite of
  50.  
  51. events.  These events, Open Application, Open Documents, Print
  52.  
  53. Documents, and Quit Application, are fully documented in Inside
  54.  
  55. Macintosh, Volume VI, and elsewhere.  Beyond that, Help on Wheels
  56.  
  57. requires no special knowledge of Apple events.
  58.  
  59. 
  60.  
  61. Client applications should be able to receive events while running in the
  62.  
  63. background.  This is not a requirement, and foreground-only applications
  64.  
  65. can still receive Help events, because the server always brings the client
  66.  
  67. into the foreground before sending a Help event.
  68.  
  69. 
  70.  
  71. For consistency, your application should support two methods of invoking
  72.  
  73. help.  First, it should add one or more entries to the Help menu which the
  74.  
  75. user can select to get help on the entire application or on a specific topic.
  76.  
  77. Second, it should react to the Help key (ASCII character value 5) and
  78.  
  79. Command-? key combination (for keyboards which lack a Help key) in all
  80.  
  81. modes, including dialogs, and in a context-sensitive fashion, displaying a
  82.  
  83. topic relevant to what the user is seeing.
  84.  
  85. 
  86.  
  87. NOTE:  Modal dialogs disable entries you place in the Help menu, and they
  88.  
  89. also prevent the client engine from bringing the server to the foreground
  90.  
  91. when the user presses the Help key.  The HoWSample source code contains
  92.  
  93. a sample modal dialog filter procedure which automatically hides and
  94.  
  95. unhides modal dialogs so that this is not a problem.
  96.  
  97. 
  98.  
  99. If your help file is separate from your application file, you are
  100.  
  101. responsible for keeping track of its movements between sessions; the
  102.  
  103. server keeps track during sessions.  One good way is to locate the help
  104.  
  105. file at registration time by resolving an alias record which is relative to
  106.  
  107. your application file.  You should store this alias record as a resource in
  108.  
  109. your application file, and keep an updated version in your preferences file
  110.  
  111. from session to session.  While resolving this alias record, you should be
  112.  
  113. careful to specify no user interaction, so the user won‚Äôt see an
  114.  
  115. AppleShare password dialog if operating with a borrowed preferences
  116.  
  117. file.  (If this all sounds confusing, take heart.  The utility function
  118.  
  119. HoWFindHelpFile in the HoWLib interface library takes care of this entire
  120.  
  121. procedure, and the HoWSample source code shows how to call it.)  To
  122.  
  123. create such an alias record while building your application, ask Finder to
  124.  
  125. make an alias to the help file, and pull the contained alias resource into
  126.  
  127. your application file using Rez.  If the help file is in a different folder from
  128.  
  129. the application file, you should first move the alias to the application
  130.  
  131. file‚Äôs folder, then do a ‚ÄúFind Original‚Äù on it to force Finder to update its
  132.  
  133. relativity data.  You should also do a ‚ÄúFind Original‚Äù to update the alias
  134.  
  135. whenever the help file‚Äôs creation date changes.  (Again, the HoWSample
  136.  
  137. source code and Make file shows how to do all this.)  If you don‚Äôt like the
  138.  
  139. approach of using alias records to track the help file, you can either
  140.  
  141. merge the help data into the application, or keep it separate and tell your
  142.  
  143. users not to move one file without the other.
  144.  
  145. 
  146.  
  147. 
  148.  
  149.